shared source/vb/language/shared/pathutilities.h

   1 //-------------------------------------------------------------------------------------------------
   2 //
   3 //  Copyright (c) Microsoft Corporation.  All rights reserved.
   4 //
   5 //  File and directory path utilities.
   6 //
   7 //-------------------------------------------------------------------------------------------------
   8
   9 #pragma once
  10
  11 #define _DEFAULTPATHSEPARATOR   L'\\'
  12 #define _DEFAULTEXTSEPARATOR    L'.'
  13
  14 //---------------------------------------------------------------------------
  15 // @@ Path utilities
  16 //
  17 // These are general purpose file-path manipulation routines.  The convention
  18 // is that the caller must allocate enough space for the path.  Typically this
  19 // is MAX_PATH characters.
  20 //
  21 // Whenever a directory is specified, then the trailing backslash (\) should
  22 // not be included as part of the string.
  23 //---------------------------------------------------------------------------
  24
  25 // A cate----zation of path types
  26 enum PathType
  27 {
  28     PathUNC,    // fully qualified UNC path
  29     PathFull,   // fully qualified path
  30     PathRelative,   // relative path
  31     PathEmpty,
  32     PathFileURL
  33 };
  34
  35 // Given a path, return one of the PathType constants.  A path is considered
  36 // to be full if it starts with <any-char>:.  A path is a UNC path if it
  37 // starts with \\.  All other paths are considered to be relative paths.
  38 PathType PathGuessType(
  39     const WCHAR * wszPath,
  40     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
  41
  42 // Given a directory or filename, add a directory or filename to the path.
  43 // This is like WszCat, only it makes sure that a '\\' separator is added
  44 // if necessary.  The return value is wszPath passed in.  For the general
  45 // case, the wszPath buffer should be MAX_PATH * 2 characters.
  46 // [....]: 10/26/2004:  It's wrong to assume that a path is a given size.  Added a specific parameter to cover this.
  47 WCHAR * PathCatName(
  48     _Inout_opt_cap_(cchPathBuffer)_Prepost_count_(cchPathBuffer)WCHAR * wszPath,
  49     size_t cchPathBuffer,
  50     _In_z_ const WCHAR * wszName,
  51     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
  52
  53 // Given a full or partial file / directory path, return a pointer to the
  54 // the filename / directory name portion of the path.
  55 //   "c:\bar\foo.txt"   returns "foo.txt"
  56 //   "c:\"        returns    ""
  57 //   "c:foo"        returns "foo"
  58 //   "c:..\foo"        returns "foo"
  59 //   "c:.."        returns ".."
  60 //   "\\bar\foo"        returns "foo"
  61 //   "\\bar\foo\----" returns "\----"
  62 //   "bar\foo.txt"    returns "bar\foo.txt"
  63 //   "foo.txt"        returns "foo.txt"
  64 WCHAR * PathFindName(
  65     const WCHAR * wszPath,
  66     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
  67
  68 // Given a full or partial file / directory path, return a pointer to
  69 // the extension portion of the filename.  This includes the period.
  70 // If there is no extension, then the pointer is to the end of the
  71 // string.
  72 //   "c:\bar\foo.txt"      returns ".txt"
  73 //   "c:\"          returns ""
  74 //   "c:\foo"          returns ""
  75 //   "c:\bar\foo.bar.txt" returns ".txt"
  76 //   "c:\bar.foo\bar"      returns ""
  77 WCHAR * PathFindExt(
  78     const WCHAR * wszPath,
  79     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR,
  80     const WCHAR wchExtSeparator = _DEFAULTEXTSEPARATOR);
  81
  82 // Given a full or partial file / directory path, return a pointer to the
  83 // the first character in the path that does not correspond to the device:
  84 //   "c:\bar\foo.txt"   returns "\bar\foo.txt"
  85 //   "c:\"        returns    "\"
  86 //   "c:foo"        returns "foo"
  87 //   "c:..\foo"        returns "..\foo"
  88 //   "c:.."        returns ".."
  89 //   "\\bar\foo"        returns ""
  90 //   "\\bar\foo\----" returns "\----"
  91 //   "bar\foo.txt"    returns "bar\foo.txt"
  92 //   "foo.txt"        returns "foo.txt"
  93 WCHAR * PathFindDevice(
  94     const WCHAR * wszPath,
  95     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
  96
  97 // Given a path pointing to a file or directory, shorten the path string to
  98 // to be just the path of the parent directory.  If there is no parent
  99 // directory, then it has no effect on the buffer.  The pointer passed
 100 // in is returned.  In no cases will the truncated path have a '\\' at
 101 // the end of it. For example:
 102 //
 103 //    "c:\a\b\c"  returns "c:\a\b"
 104 //    "\\a\\b"      returns "\\a\\b"
 105 //    "\\a\\b\c"  returns "\\a\\b"
 106 //    "c:\a\b"      returns "c:\a"
 107 //    "c:\"      returns "c:
 108 //    "c:\a"      returns "c:
 109 //
 110 // This returns whether or not the buffer was modified.
 111 BOOL PathMakeDir(
 112     _Inout_opt_z_ WCHAR * wszPath,
 113     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
 114
 115 // Takes the (possibly-qualified) file name in pwszFileName and puts a canonical version
 116 // of the file name (no path, all lowercase) into pwszCanonicalBuf, which must be at
 117 // least cch Unicode characters in size.  The function modifies and returns pwszCanonicalBuf.
 118 WCHAR * GetCanonicalFileName(
 119     _In_opt_z_ const WCHAR * pwszFileName,
 120     _Out_opt_cap_(cch)WCHAR * pwszCanonicalBuf,
 121     unsigned cch,
 122     const WCHAR wchPathSeparator = _DEFAULTPATHSEPARATOR);
 123
 124 unsigned VB_W_GetCommandLine(
 125     _Out_opt_cap_(SizeOfBuffer)WCHAR * pwszBufferForCommandLine,
 126     unsigned SizeOfBuffer);
 127
 128 bool IsIllegalFileNameChar(const WCHAR wch);